﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="KeyboardApi.cs" company="Marek Dzikiewicz">
//   Marek Dzikiewicz, All Rights Reserved.
// </copyright>
// --------------------------------------------------------------------------------------------------------------------

namespace Dzikiewicz.WinApi.User.Keyboard
{
    using System;
    using System.Runtime.InteropServices;

    /// <summary>
    /// Exposes keyboard-related WinAPI functions.
    /// </summary>
    public static class KeyboardApi
    {
        /// <summary>
        /// Defines a system-wide hot key.
        /// </summary>
        /// <param name="hwnd">
        /// A handle to the window that will receive <c>WM_HOTKEY</c> messages generated by the hot key. If this 
        /// parameter is <c>NULL</c>, <c>WM_HOTKEY</c> messages are posted to the message queue of the calling thread 
        /// and must be processed in the message loop.
        /// </param>
        /// <param name="id">
        /// The identifier of the hot key. If the hWnd parameter is <c>NULL</c>, then the hot key is associated with 
        /// the current thread rather than with a particular window. If a hot key already exists with the same hWnd 
        /// and id parameters, see Remarks for the action taken.
        /// </param>
        /// <param name="modifiers">
        /// The keys that must be pressed in combination with the key specified by the <c>vk</c> parameter in order to 
        /// generate the <c>WM_HOTKEY</c> message. The modifiers parameter can be a combination of the values defined
        /// in enum <see cref="KeyModifiers"/>.
        /// </param>
        /// <param name="vk">
        /// The virtual-key code of the hot key. 
        /// See Virtual Key Codes (http://msdn.microsoft.com/en-us/library/dd375731(VS.85).aspx).
        /// </param>
        /// <returns>
        /// If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. 
        /// To get extended error information, call <c>GetLastError</c>.
        /// </returns>
        [DllImport("user32", SetLastError = true)]
        public static extern int RegisterHotKey(IntPtr hwnd, int id, int modifiers, int vk);

        /// <summary>
        /// Frees a hot key previously registered by the calling thread.
        /// </summary>
        /// <param name="hwnd">
        /// A handle to the window associated with the hot key to be freed. This parameter should be <c>NULL</c> if 
        /// the hot key is not associated with a window.
        /// </param>
        /// <param name="id">The identifier of the hot key to be freed.</param>
        /// <returns>
        /// If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. 
        /// To get extended error information, call <c>GetLastError</c>.
        /// </returns>
        [DllImport("user32", SetLastError = true)]
        public static extern int UnregisterHotKey(IntPtr hwnd, int id);
    }
}